Skip to main content

FAQ

General​

  • What is an Aspect?

    An Aspect is a JavaScript file that Candescent dynamically injects into the Digital Banking platform at runtime. It can modify the page, add widgets, or integrate third-party services.

  • Do Aspects work on mobile?

    On mobile (native or React Native), Aspects run inside a WebView and function as overlays. They do not have direct DOM-level access like they do on the web. For details on the differences, see the Mobile Technical Reference.

  • What does Candescent expect from the FI?

    The FI must provide the JavaScript file (or a URL to it) along with any vendor-specific URLs and configuration details. This includes the JS file URL and domain information for whitelisting.

  • How do I submit an Aspect for review?

    Use the Submissions feature in the Developer Console. See Submissions for the full workflow.

Implementation​

  • Do we need to write custom JavaScript?

    Yes. Use the examples from the Web Examples or Mobile Examples as a starting point and replace placeholders with your actual URLs and configuration values.

  • Do we need to create custom HTML?

    For web, no — the HTML wrapper is handled by the platform. For mobile, yes — mobile Aspects are delivered as full HTML documents. See the Mobile Technical Reference for the required structure.

  • How do I choose between context-less and context-aware?

    If your integration does not need to know who the user is (e.g., anonymous chat, styling changes), use a context-less Aspect. If it needs user identity (e.g., personalized chat, account-specific features), use a context-aware Aspect.

  • When should I use global variables vs. OIDC?

    Use global variables (dbk.sessionInfo()) for quick, non-security-critical access to user info like name or GUID. Use the OIDC method when your integration requires verified, trusted user identity — for example, when your backend needs to confirm who the user is before performing an action.

  • I need to support both web and mobile. Do I need two separate Aspects?

    Yes. Web and mobile use fundamentally different execution models, authentication patterns, and layout management. See the side-by-side comparison for a step-by-step mapping.

OIDC for Aspects​

  • How is the Aspects OIDC flow different from the standard OIDC integration?

    The Aspects flow uses a dedicated endpoint (/feng-bff/beta/v1/aspect/token) that returns an authorization code directly to the in-page script, since Aspects cannot handle browser redirects. Your backend then exchanges this code using the same centralized token endpoint as the standard OIDC flow.

  • Can I call the Candescent API gateway directly from the Aspect (front-end)?

    No. The Aspect should only obtain the authorization code. All token exchange and API calls must happen on your backend server.

  • Where can I find the full OIDC specification (token exchange, claims, validation)?

    See the OIDC Integration Technical Reference. The token exchange, ID token validation, supported claims, and security requirements documented there apply to the Aspects OIDC flow as well.

Troubleshooting​

  • Candescent Forge CLI: multiline --message for templates (forge aspect preview, forge aspect submit).

    In bash and zsh, use ANSI-C quoting — $'...' — so \n becomes a real newline in the argument. Example:

    Bash
    forge aspect preview --template banner --message $'Headline\nSecond line'

    In plain single-quoted strings ('...\n...'), the shell does not interpret \n; you get a backslash and the letter n. See also the Forge CLI README troubleshooting section for this CLI.

  • My Aspect script is not loading.

    Verify that the script URL is accessible and that the domain is whitelisted in the platform configuration.

  • dbk.sessionInfo() returns undefined.

    The user may not be logged in, or the session data has not yet been initialized. Ensure your script runs after the platform has fully loaded and the user is authenticated.

  • The authorization code request fails.

    Check that your clientId is correct, the FI domain in the URL matches the environment, and the user has an active session (the request relies on the session cookie).

  • My mobile Aspect's WebView is the wrong size.

    Verify that you are calling resizeWindow() via the sizeAndLocation bridge with correct aspectLocations coordinates. Make sure condenseWindow() is called on initialization and expandWindow() is called when the widget opens. See the Window Size Negotiation section.

  • Candescent Forge CLI: context-aware template shows fallback text.

    Context-aware templates (welcome-banner, personalized-toast) use dbk.sessionInfo() to personalize content. This is only available in the OLB Docker playground. If you use --no-playground (local mock server), the template falls back to generic text like "Valued Customer". Run without --no-playground for live data:

    Bash
    forge aspect preview --template welcome-banner --message 'Check our new savings rates!'

  • Candescent Forge CLI: mobile Aspect preview limitations.

    Mobile Aspects run as HTML documents inside a native WebView. The CLI's --platform mobile flag saves the generated HTML and opens it in a desktop browser for visual verification. Native bridge features (sizeAndLocation, tokenApiDetails) require testing in a real mobile WebView. For testing, use the Expo mobile sandbox or a physical device.

  • Candescent Forge CLI: platform validation error on submit.

    If you see "was built for web" / "was built for mobile" during forge aspect submit, it means the --platform you specified does not match the platform recorded when you created/previewed the Aspect. Either rebuild the Aspect with the correct --platform or use --force to skip validation.

Security​

  • Are Aspect templates protected against XSS?

    Yes — context-aware templates emitted by forge aspect preview (welcome-banner, personalized-toast) inline runtime validators that check dbk.sessionInfo() for type, length (≤ 200 chars), and a Unicode character allowlist, then HTML-escape the result before any DOM insertion. The configured message argument is also escaped at template generation time. If validation fails, the template falls back to a safe default ("Valued Customer" / "there"). For details and reference helpers, see the Web security model.

  • What protocols does the modal and card templates' ctaUrl accept?

    Only http: and https:. Both templates route the URL through the runtime __cdxValidateHttpUrl helper; anything else (javascript:, data:, vbscript:, file:, etc.) is rejected. The modal dismisses with an error logged to the console; the card falls back to href="#" so the link is harmless. (The card protocol filter was back-ported in Phase 6 — earlier versions inlined <a href="${ctaUrl}"> directly into HTML.)

  • Will Forge-generated Aspects work under a strict CSP (script-src 'self')?

    Yes. As of Phase 6, every emitted snippet is free of inline onclick= / onerror= / onload= handlers — close and dismiss buttons use data-cdx-action attributes plus addEventListener. The full template catalog runs under script-src 'self' without requiring 'unsafe-inline'. Vendor-loader templates (vendor-script-loader, tag-manager, etc.) inherit the vendor SDK's CSP behavior — coordinate with the vendor.

  • What about style-src 'self' — the templates inject <style> blocks for keyframes?

    Pass --csp-nonce <value> with the host page's per-request nonce. Every emitted <style> element gets the matching nonce attribute so it runs under style-src 'nonce-<value>':

    Bash
    forge aspect preview --template banner --csp-nonce "$REQUEST_NONCE"

    Validation: 1 – 256 chars, no whitespace / quotes / brackets / backticks. A malformed nonce yields a runtime console.error and the attribute is omitted (fail-open). See CSP nonce for inline <style>.

  • How do I check the security posture of an Aspect before deployment?

    Run forge aspect verify — it codifies every grep recipe in the Deployment Security Checklist into a single command. Use --strict --template <id> in CI to gate submissions on any missing required control. The checklist itself remains the canonical reviewer worksheet (with sign-off lines); the Security Questionnaire (Vendor Response) ships per-template completed answers to all 60 vendor-due-diligence questions so AppSec teams have a copy-pasteable answer set rather than re-deriving every answer.

  • A developer edited a generated Aspect — how do I know they didn't break a security control?

    Bash
    forge aspect verify ./aspects/edited.js --template <original-template-id> --strict

    Returns exit 1 on any missing required control with a hint explaining the impact. Wire this into your pre-commit hook or CI pipeline. See the verify command docs for full usage.

  • Can I pin vendor SDKs with Subresource Integrity?

    Yes — pass --integrity 'sha{256,384,512}-<base64>' (and optionally --crossorigin) to forge aspect preview or forge aspect submit. The five vendor-loader templates (vendor-script-loader, vendor-script-with-config, tag-manager, vendor-sdk-personalized, mobile-vendor-chat-jsbridge) accept it. vendor-script-with-config additionally accepts --css-integrity / --css-crossorigin for the CSS <link>. When SRI is configured, the template bypasses dbk.loadScript (which can't apply integrity) and emits a <script> tag with the integrity + crossOrigin attributes. A malformed hash is rejected at generation time and logged at runtime so the script still loads — fail open, never fail to load. See the Web security model for the openssl recipe and full behavior notes.

  • How do I generate the SRI hash for my vendor SDK?

    Bash
    curl -s https://cdn.your-vendor.com/sdk.js \
      | openssl dgst -sha384 -binary \
      | openssl base64 -A \
      | sed 's/^/sha384-/'

    Re-run when the vendor publishes a new SDK version. Coordinate a stable release URL with the vendor first if they ship frequent silent updates — every content change requires a new hash.

  • How does hidden-iframe-sso protect against forged token messages?

    Three layers, all enforced at runtime: (1) the iframe is rendered with a minimal sandbox attribute (allow-same-origin allow-scripts by default — override with --iframe-sandbox); (2) postMessage events are matched against an inlined origin allowlist (the iframe's own origin is always trusted; extend with --allowed-origins 'https://idp.partner.com,*.federation.example.com'); (3) the token payload is validated against a strict schema (type === 'sso-token', non-empty token ≤ 4096 chars, future expiry, optional ≤ 1024-char signature) and unknown fields are stripped before dispatch. The custom event uses bubbles:false / composed:false so it does not cross shadow-DOM boundaries. See the SSO iframe hardening section in the Web technical reference.

  • My SSO endpoint posts back from a different origin than the iframe URL — how do I trust it?

    Use --allowed-origins:

    Bash
    forge aspect preview --template hidden-iframe-sso \
      --iframe-src 'https://sso.bank.example.com/handoff' \
      --allowed-origins 'https://idp.partner.com, *.federation.example.com'

    Wildcards take the form *.domain.tld (subdomain match). Invalid entries (non-URL strings, non-http(s): protocols) are dropped silently at generation time so they never make it into the runtime allowlist.

  • My vendor's iframe needs to submit a form / open a popup — can I relax the sandbox?

    Yes — pass --iframe-sandbox with the additional tokens:

    Bash
    forge aspect preview --template hidden-iframe-sso \
      --iframe-sandbox 'allow-same-origin allow-scripts allow-forms'

    Avoid allow-popups and allow-top-navigation unless absolutely required — they widen the iframe's reach to the parent context. The CLI validates tokens against the WHATWG list; unknown tokens fall back to the default with a console.error.

  • The OIDC token endpoint is slow / flaky — how do I tune timeouts and retries?

    Pass --timeout-ms, --max-retries, and --retry-delay-ms:

    Bash
    forge aspect preview --template oidc-snippet \
      --client-id my-app --fi-domain acmebank \
      --timeout-ms 30000 --max-retries 5 --retry-delay-ms 2000

    Defaults are 10 s timeout / 3 retries / 1 s initial delay (backoff doubles each attempt, capped at 8 s). 4xx errors are never retried — that means a misconfigured clientId fails fast. Out-of-range values (--timeout-ms 999, --max-retries 99) are dropped silently and the template falls back to defaults. The same flags apply to the JSBridge fallback fetch in mobile-vendor-chat-jsbridge. See the Fetch resiliency section.

  • My OIDC request keeps timing out — how do I tell from the toast?

    The oidc-snippet template's error toast distinguishes a timeout from other failures: when the AbortController fires, the message reads "Request timed out after <ms>ms" and the hint suggests --timeout-ms. Other error messages (HTTP 4xx/5xx, network unreachable) show the original error and a generic "Check the console and ensure the toolkit is running" hint. You'll also see [cdx-aspect] OIDC error: Request timed out after 10000ms in the console.

  • Can I disable retries entirely?

    Yes — pass --max-retries 0. The template then performs a single fetch with the configured timeout and surfaces any error immediately. Useful for tight latency budgets or when you'd rather bubble the failure to a higher-level retry handler.

  • How do I trace a browser console error back to a specific Aspect deployment?

    Look at the prefix on the log line. The three templates that cross trust boundaries — oidc-snippet, mobile-vendor-chat-jsbridge, hidden-iframe-sso — bake a per-snippet correlation id into every console.* line they emit:

    [cdx-aspect:aspect_lt6m8n2p_xY9zKqAB] OIDC error: Request timed out after 10000ms

    The id is auto-generated at template-generation time and is stable for the lifetime of that snippet. Override via --correlation-id <value> to chain logs from your CI / release pipeline:

    Bash
    forge aspect submit "auth" --template oidc-snippet --correlation-id "$RELEASE_ID" ...

    Other templates (banner, toast, card, vendor-loaders, etc.) keep the legacy [cdx-aspect] prefix without a per-instance id — they don't cross trust boundaries or call external services. See Correlation IDs for incident response.

  • What is the dbk API contract — what methods are available and when?

    The host shell exposes a small window.dbk API for Aspects to read session context, load scripts, and detect WebViews. Forge templates always check for availability before use and degrade gracefully when running outside the host. See the dbk API contract table in the Web technical reference for the full method list, availability per platform, fallback behavior, and security properties.

  • What security work is not yet covered by the CLI?

    Shadow DOM CSS isolation (so parent-page styles can't leak into Aspect UI), HMAC verification on the SSO signature field (currently type-checked only), and a consolidated security-architecture diagram + FI deployment checklist (Phase 8 deliverable). These are tracked in SECURITY_IMPLEMENTATION_PLAN.md in the cdx-forge-cli repository. Until they land, hand-author equivalents or treat them as manual review items.

Contact & Support​

For questions or support, reach out to your assigned Candescent Integration PM via Marketplace.